/*
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 * 
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 * 
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
 */
 
package org.erossi.common.model;

import java.io.Serializable;
import java.util.List;

/**
 * 'GenericDAO' interface: interfaccia che rappresenta il tipo generico di oggetto DAO. 
 * 
 * <p>
 *   L'interfaccia utilizza una definzione generica per consentire un maggiore controllo sui tipi a compile-time.
 * <p>
 * <p>
 *   I tipi generici parametrizzati sono:
 *   <ul>
 *     <li><code>T</code> generica rappresentazione del tipo di bean di cui il DAO in oggetto sarà il wrap;
 *     <li><code>ID</code> generica rappresentazione del tipo di dato con cui identificare univocamente
 *       il bean. Nella maggioranza dei casi, il tipo <code>ID</code> sarà concretizzato da un tipo
 *       {@link java.lang.Long}
 *   </ul>
 * </p>
 *
 * @author erossi
 * @version Feb 9, 2007
 */
public interface GenericDAO<T, ID extends Serializable> {

  /**
   * Effettua la ricerca per identificativo del bean.
   * 
   * @param id l'identificativo <code>id</code> del bean
   * @param lock flag da impostare al valore <code>true</code> nel caso in cui si intenda
   *   effettuare un lock sulla base dati per procedere eventualmente all'update successivo.
   * @return il bean corrispondente all'identificativo passato.
   */
  public T cercaPerId(ID id, boolean lock);

  /**
   * Recupera l'elenco completo dei bean.
   * 
   * @return una lista contenente tutti i bean
   */
  public List<T> cercaTutti();

  /**
   * Effettua la ricerca utilizzando il bean passato come "esempio/criterio".
   *  
   * <p>Se il bean contiene un attributo valorizzato, come criterio,
   *   verranno tornati tutti i bean con il medesimo attributo valorizzato con il medesimo valore.</p>
   *    
   * @param esempio il bean da utilizzare come esempio/criterio
   * @param attributiEsclusi elenco degli attributi esclusi dal matching con il filtro.
   * @return la lista dei bean che soddisfano l'"esempio/criterio".
   */
  public List<T> cercaPerEsempio(T esempio, String[] attributiEsclusi);

  /**
   * Registra un bean.
   * 
   * <p>
   *   Procede automaticamente alle operazioni di inserimento
   *   od aggiornamento, se necessario.
   * </p>
   * 
   * @param bean il bean da registrare
   * @return il bean registrato
   */
  public T registra(T bean);

  /**
   * Cancella un bean.
   * 
   * <p>
   *   Procede all'eliminazione del bean dal dominio della persistenza.
   * </p>
   *  
   * @param bean il bean da cancellare
   */
  public void cancella(T bean);

}

